<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="testresult-objects.html" />
<link rel="parent" href="module-unittest.html" />
<link rel="next" href="module-test.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>23.3.8 TestLoader Objects </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.3.7 testresult Objects"
  href="testresult-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.3 unittest  "
  href="module-unittest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.4 test  "
  href="module-test.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="testresult-objects.html">23.3.7 TestResult Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-unittest.html">23.3 unittest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-test.html">23.4 test  </a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0025380000000000000000"></a><a name="testloader-objects"></a>
<br>
23.3.8 TestLoader Objects
            
</h2>

<p>
The <tt class="class">TestLoader</tt> class is used to create test suites from
classes and modules.  Normally, there is no need to create an instance
of this class; the <tt class="module"><a href="module-unittest.html">unittest</a></tt> module provides an instance
that can be shared as <code>unittest.defaultTestLoader</code>.
Using a subclass or instance, however, allows customization of some
configurable properties.

<p>
<tt class="class">TestLoader</tt> objects have the following methods:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5051' xml:id='l2h-5051' class="method">loadTestsFromTestCase</tt></b>(</nobr></td>
  <td><var>testCaseClass</var>)</td></tr></table></dt>
<dd>
  Return a suite of all tests cases contained in the
  <tt class="class">TestCase</tt>-derived <tt class="class">testCaseClass</tt>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5052' xml:id='l2h-5052' class="method">loadTestsFromModule</tt></b>(</nobr></td>
  <td><var>module</var>)</td></tr></table></dt>
<dd>
  Return a suite of all tests cases contained in the given module.
  This method searches <var>module</var> for classes derived from
  <tt class="class">TestCase</tt> and creates an instance of the class for each test
  method defined for the class.

<p>
<span class="warning"><b class="label">Warning:</b>
While using a hierarchy of
  <tt class="class">TestCase</tt>-derived classes can be convenient in sharing
  fixtures and helper functions, defining test methods on base classes
  that are not intended to be instantiated directly does not play well
  with this method.  Doing so, however, can be useful when the
  fixtures are different and defined in subclasses.</span>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5053' xml:id='l2h-5053' class="method">loadTestsFromName</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, module</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Return a suite of all tests cases given a string specifier.

<p>
The specifier <var>name</var> is a ``dotted name'' that may resolve
  either to a module, a test case class, a test method within a test
  case class, a <tt class="class">TestSuite</tt> instance, or a callable object which
  returns a <tt class="class">TestCase</tt> or <tt class="class">TestSuite</tt> instance.  These checks
  are applied in the order listed here; that is, a method on a possible
  test case class will be picked up as ``a test method within a test
  case class'', rather than ``a callable object''.

<p>
For example, if you have a module <tt class="module">SampleTests</tt> containing a
  <tt class="class">TestCase</tt>-derived class <tt class="class">SampleTestCase</tt> with three test
  methods (<tt class="method">test_one()</tt>, <tt class="method">test_two()</tt>, and
  <tt class="method">test_three()</tt>), the specifier <code>'SampleTests.SampleTestCase'</code>
  would cause this method to return a suite which will run all three test
  methods.  Using the specifier <code>'SampleTests.SampleTestCase.test_two'</code>
  would cause it to return a test suite which will run only the
  <tt class="method">test_two()</tt> test method.  The specifier can refer to modules
  and packages which have not been imported; they will be imported as
  a side-effect.

<p>
The method optionally resolves <var>name</var> relative to the given
  <var>module</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5054' xml:id='l2h-5054' class="method">loadTestsFromNames</tt></b>(</nobr></td>
  <td><var>names</var><big>[</big><var>, module</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Similar to <tt class="method">loadTestsFromName()</tt>, but takes a sequence of
  names rather than a single name.  The return value is a test suite
  which supports all the tests defined for each name.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5055' xml:id='l2h-5055' class="method">getTestCaseNames</tt></b>(</nobr></td>
  <td><var>testCaseClass</var>)</td></tr></table></dt>
<dd>
  Return a sorted sequence of method names found within
  <var>testCaseClass</var>; this should be a subclass of <tt class="class">TestCase</tt>.
</dl>

<p>
The following attributes of a <tt class="class">TestLoader</tt> can be configured
either by subclassing or assignment on an instance:

<p>
<dl><dt><b><tt id='l2h-5056' xml:id='l2h-5056' class="member">testMethodPrefix</tt></b></dt>
<dd>
  String giving the prefix of method names which will be interpreted
  as test methods.  The default value is <code>'test'</code>.

<p>
This affects <tt class="method">getTestCaseNames()</tt> and all the
  <tt class="method">loadTestsFrom*()</tt> methods.
</dl>

<p>
<dl><dt><b><tt id='l2h-5057' xml:id='l2h-5057' class="member">sortTestMethodsUsing</tt></b></dt>
<dd>
  Function to be used to compare method names when sorting them in
  <tt class="method">getTestCaseNames()</tt> and all the <tt class="method">loadTestsFrom*()</tt> methods.
  The default value is the built-in <tt class="function">cmp()</tt> function; the attribute
  can also be set to <tt class="constant">None</tt> to disable the sort.
</dl>

<p>
<dl><dt><b><tt id='l2h-5058' xml:id='l2h-5058' class="member">suiteClass</tt></b></dt>
<dd>
  Callable object that constructs a test suite from a list of tests.
  No methods on the resulting object are needed.  The default value is
  the <tt class="class">TestSuite</tt> class.

<p>
This affects all the <tt class="method">loadTestsFrom*()</tt> methods.
</dl>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.3.7 testresult Objects"
  href="testresult-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.3 unittest  "
  href="module-unittest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.4 test  "
  href="module-test.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="testresult-objects.html">23.3.7 TestResult Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-unittest.html">23.3 unittest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-test.html">23.4 test  </a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
